HOW TO – Using Kourier to Create a REST Client Applet

Kourier Integrator Online Help

HOW TO – Using Kourier to Create a REST Client Applet

Project Description

You would like to include some basic weather information such as temperature, wind speed, wind direction, etc. in your application by accessing one of the many REST-based APIs in the cloud.

Assumptions

This example shows how to accomplish this project using Kourier as a REST client application. It assumes that:

The Weather Underground API called “conditions” will be used to acquire current weather information.
The application has a way to determine the city and state of a logged in user. Those two pieces of information are required inputs to the “conditions” API.

Setup

Setup a DSN that points to the base URL endpoint for the Weather Underground API. Using only the base URL allows the programmer to append additional API information to the end of the base URL. Here is what the DSN looks like:

The information returned from the “conditions” API is quite complex. Fortunately, Kourier has a great way of parsing complex XML documents via an Import Specification. Here is the Import Specification that will parse the XML into a dynamic array:

Sample Program

Here is a sample program that pulls all the pieces together.

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.

    $INCLUDE KORE-INCLUDES XML.DEFFUN
    PROMPT ''
    PRINT 'Enter City: ':
    INPUT CITY
    IF UPCASE(CITY) = '.E' THEN STOP
    CITY = TRIM(CITY)
    CONVERT ' ' TO '_' IN CITY; * API requires spaces converted to underscore
*
    PRINT 'Enter State: ':
    INPUT STATE
    IF UPCASE(STATE) = '.E' THEN STOP
*
    DSN.ID   = 'WU_HTTP'
    HTTPVERB = 'GET'
    URL      = 'conditions/q/':STATE:'/':CITY:'.xml'
    INHDRS   = ''
    INDATA   = ''
    OUTHDRS  = ''
 *
    CALL KMK.HTTPSUBMIT(DSN.ID, HTTPVERB, URL, INHDRS, INDATA, OUTHDRS, XML, HTTPSTATUS, OPTHDRS, ERR, PARAMS)
    IF ERR # '' THEN GOTO FatalError
 *
    CALL KMK.IMPORTPARSE('WU_CONDITIONS',XML,RESULT,APPERRS,ERR,PARAMS)
    IF ERR # '' THEN GOTO FatalError
    IF APPERRS # '' THEN GOTO AppError
    RESULT = RAISE(RESULT)
*
    PSTATUS = XML.XPATH(XML,'wind_mph',WIND.MPH,ERR,PARAMS)
    IF PSTATUS THEN GOTO FatalError
*
    PSTATUS = XML.XPATH(XML,'wind_dir',WIND.DIR,ERR,PARAMS)
    IF PSTATUS THEN GOTO FatalError
*
    PRINT 'Display Location......: ':RESULT<1>
    PRINT 'Display Latitude......: ':RESULT<2>
    PRINT 'Display Longitude.....: ':RESULT<3>
    PRINT 'Observation Location..: ':RESULT<4>
    PRINT 'Observation Latitude..: ':RESULT<5>
    PRINT 'Observation Longitude.: ':RESULT<6>
    PRINT 'Temperature...........: ':RESULT<7>
    PRINT 'Wind Speed............: ':WIND.MPH
    PRINT 'Wind Direction........: ':WIND.DIR
*
    STOP

Line 001 of the program includes Kourier’s XML function declarations. This is required to use the XML.XPATH function that is invoked later in the program.

Lines 002 thru 011 prompt the user for a city and a state. Note that the city name has all spaces converted to the underscore character with is a requirement of the “conditions” API.

Lines 013 thru 018 setup the variables that will be passed to the KMK.HTTPSUBMIT subroutine. The URL variable created on line 015 will be appended to the base URL configured in the WU_HTTP DSN. Line 020 calls the KMK.HTTPSUBMIT subroutine which returns the results of the REST request returned by the “conditions” API in the XML variable.

Line 023 is used to call the KMK.IMPORTPARSE routine which creates a dynamic array based upon the fields included in the WU_CONDITIONS Import Specification. The KMK.IMPORTPARSE routine can return information for more than on record, if it exists in source XML, so line 026 raises all system delimiters one level since the “conditions” API only returns information for a single city/state combination.

Lines 028 thru 032 show how the XML.XPATH function can be used to return information from the source XML using standard Kourier XPATH syntax.

Finally, line 34 thru 42 displays the information returned from the “conditions” API.

Sample XML for “conditions” API (some nodes have been removed to protect the innocent)

<response>

   <current_observation>

     <display_location>

	<full>San Diego, CA</full>

	<city>San Diego</city>

	<state>CA</state>

	<state_name>California</state_name>

	<country>US</country>

	<country_iso3166>US</country_iso3166>

	<zip>92101</zip>

	<magic>1</magic>

	<wmo>99999</wmo>

	<latitude>32.72109985</latitude>

	<longitude>-117.16430664</longitude>

	<elevation>16.00000000</elevation>

     </display_location>

     <observation_location>

	<full>Embarcadero North, San Diego, California</full>

	<city>Embarcadero North, San Diego</city>

	<state>California</state>

	<country>US</country>

	<country_iso3166>US</country_iso3166>

	<latitude>32.717541</latitude>

	<longitude>-117.170952</longitude>

	<elevation>10 ft</elevation>

     </observation_location>

     <station_id>KCASANDI123</station_id>

     <observation_time>Last Updated on March 2, 3:39 PM PST</observation_time>

     <observation_time_rfc822>Wed, 02 Mar 2016 15:39:14 -0800</observation_time_rfc822>

     <observation_epoch>1456961954</observation_epoch>

     <weather>Mostly Cloudy</weather>

     <temperature_string>63.4 F (17.4 C)</temperature_string>

     <temp_f>63.4</temp_f>

     <temp_c>17.4</temp_c>

     <relative_humidity>75%</relative_humidity>

     <wind_string>From the West at 4.9 MPH Gusting to 6.3 MPH</wind_string>

     <wind_dir>West</wind_dir>

     <wind_degrees>270</wind_degrees>

     <wind_mph>4.9</wind_mph>

     <wind_gust_mph>6.3</wind_gust_mph>

     <wind_kph>7.9</wind_kph>

     <wind_gust_kph>10.1</wind_gust_kph>

     <feelslike_string>63.4 F (17.4 C)</feelslike_string>

     <feelslike_f>63.4</feelslike_f>

     <feelslike_c>17.4</feelslike_c>

     <visibility_mi>10.0</visibility_mi>

     <visibility_km>16.1</visibility_km>

     <precip_1hr_string>0.00 in ( 0 mm)</precip_1hr_string>

     <precip_1hr_in>0.00</precip_1hr_in>

     <precip_1hr_metric> 0</precip_1hr_metric>

     <precip_today_string>0.00 in (0 mm)</precip_today_string>

     <precip_today_in>0.00</precip_today_in>

     <precip_today_metric>0</precip_today_metric>

     <icon>mostlycloudy</icon>

     <icon_url>http://icons.wxug.com/i/c/k/mostlycloudy.gif</icon_url>

     <forecast_url>http://www.wunderground.com/US/CA/San_Diego.html</forecast_url>

    </current_observation>

</response>